---
title: Astro v4로 업그레이드
description: 프로젝트를 최신 버전의 Astro (v4.0)로 업그레이드하는 방법
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

이 안내서는 Astro v3에서 Astro v4로 마이그레이션하는 데 도움이 됩니다.

이전 프로젝트를 v3으로 업그레이드해야 합니까? [이전 마이그레이션 안내서](/ko/guides/upgrade-to/v3/)를 참조하세요.

v3 문서를 확인해야 합니까? [이전 버전의 문서 사이트(관리되지 않는 v3.6 스냅샷)](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/)를 방문하세요.

## Astro 업그레이드

패키지 관리자를 사용하여 프로젝트의 Astro 버전과 모든 공식 통합을 최신 버전으로 업데이트하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드합니다.
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드합니다.
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # Astro와 공식 통합을 함께 업그레이드합니다.
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>

필요한 경우 [Astro 통합을 수동으로 업그레이드](/ko/guides/integrations-guide/#수동-업그레이드)할 수도 있으며 프로젝트의 다른 종속성을 업그레이드해야 할 수도 있습니다.

:::note[계속해야 합니까?]
Astro를 최신 버전으로 업그레이드한 후에는 프로젝트를 변경할 필요가 없을 수도 있습니다!

그러나 오류나 예상치 못한 동작이 발견되면 아래에서 업데이트가 필요할 수 있는 변경 사항을 확인하세요.
:::

Astro v4.0에서는 [잠재적 주요 변경 사항](#주요-변경-사항)이 포함되고, [더 이상 사용되지 않는 일부 기능이 제거](#더-이상-사용되지-않는-기능-제거)되었습니다.

v4.0으로 업그레이드한 후 프로젝트가 예상대로 작동하지 않으면 이 안내서에서 모든 주요 변경 사항에 대한 개요와 코드베이스를 업데이트 방법에 대한 지침을 확인하세요.

전체 릴리스 정보는 [변경 로그](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md)를 참조하세요.

## Astro v4.0 실험적 플래그가 제거됨

`devOverlay` 실험적 플래그를 제거하고 모든 `i18n` 구성을 `astro.config.mjs` 파일의 최상위 수준으로 이동합니다.

```js del={5-9} ins={11-14} title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})
```

`i18n` 및 이름이 변경된 `devToolbar` 구성은 이제 Astro v4.0에서 사용할 수 있습니다.

[v4.0 블로그 게시물](https://astro.build/blog/astro-4/)에서 이 두 가지 흥미로운 기능과 자세한 내용을 읽어보세요!

## 업그레이드

Astro의 종속성에 대한 주요 업그레이드로 인해 프로젝트가 크게 변경될 수 있습니다.

### 업그레이드: Vite 5.0

Astro v3.0에서는 Vite 4가 개발 서버 및 프로덕션 번들러로 사용되었습니다.

Astro v4.0에서는 Vite 4에서 Vite 5로 업그레이드되었습니다.

#### 무엇을 해야 하나요?

Vite 특정 플러그인, 구성 또는 API를 사용하는 경우 [Vite 마이그레이션 안내서](https://ko.vitejs.dev/guide/migration.html)에서 주요 변경 사항을 확인하고 필요에 따라 프로젝트를 업그레이드하세요. Astro 자체에는 큰 변화가 없습니다.

### 업그레이드: unified, remark, rehype 종속성

Astro v3.x에서는 unified v10 및 호환되는 remark/rehype 패키지를 사용하여 Markdown 및 MDX를 처리했습니다.

Astro v4.0은 [unified를 v11로](https://github.com/unifiedjs/unified/releases/tag/11.0.0) 업그레이드하며, remark/rehype 패키지를 최신 버전으로 업그레이드합니다.

#### 무엇을 해야 하나요?

사용자 정의 remark/rehype 패키지를 사용하는 경우, 패키지 관리자를 사용하여 모든 패키지를 최신 버전으로 업데이트하여 unified v11을 지원하는지 확인하세요. 사용 중인 패키지는 `astro.config.mjs`에서 찾을 수 있습니다.

적극적으로 업데이트된 패키지를 사용하는 경우, 주요 변경 사항이 없어야 하지만 일부 패키지는 아직 unified v11과 호환되지 않을 수 있습니다.
배포하기 전에 Markdown/MDX 페이지를 시각적으로 검사하여 사이트가 의도한 대로 작동하는지 확인하세요.

## 주요 변경 사항

다음 변경 사항은 Astro의 주요 변경 사항으로 간주됩니다. 주요 변경 사항은 일시적으로 이전 버전과의 호환성을 제공할 수도 있고 제공하지 않을 수도 있으며, 모든 문서는 현재 지원되는 코드만 참조하도록 업데이트됩니다.

v3.x 프로젝트에 대한 문서를 참조해야 하는 경우, [v4.0이 릴리스되기 전 문서의 (유지관리되지 않는) 스냅샷](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/)을 찾아볼 수 있습니다.

### 이름이 변경됨: `entrypoint` (통합 API)

Astro v3.x에서는 경로 진입점을 지정하는 `injectRoute` 통합 API의 속성 이름이 `entryPoint`였습니다.

Astro v4.0에서는 다른 Astro API와 일관성을 유지하기 위해 이 속성의 이름을 `entrypoint`로 변경했습니다. `entryPoint` 속성은 더 이상 사용되지 않지만 계속 작동하며 코드를 업데이트하라는 경고를 기록합니다.

#### 무엇을 해야 하나요?

`injectRoute` API를 사용하는 통합이 있는 경우 `entryPoint` 속성의 이름을 `entrypoint`로 바꿉니다. Astro 3과 4 버전을 모두 지원하는 라이브러리 작성자인 경우, `entryPoint`와 `entrypoint`를 모두 지정할 수 있습니다. 이 경우 경고가 기록되지 않습니다.

```js ins={4} del={3}
injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});
```

### 변경됨: 통합 API의 `app.render` 시그니처

Astro v3.0에서 `app.render()` 메서드는 `routeData`와 `locals`를 별도의 선택적 인수로 허용했습니다.

Astro v4.0은 `app.render()` 시그니처를 변경합니다. 이제 이 두 가지 속성을 단일 객체에서 사용할 수 있습니다. 객체와 이 두 속성은 모두 선택 사항입니다.

#### 무엇을 해야 하나요?

어댑터를 유지 관리하는 경우, 현재 시그니처는 다음 주요 버전까지 계속 작동합니다. 새 시그니처로 마이그레이션하려면 객체의 속성으로 여러 개의 독립 인수가 아닌 `routeData` 및 `locals`를 전달하세요.

```diff lang="js"
- app.render(request, routeData, locals)
+ app.render(request, { routeData, locals })
```
### 변경됨: 이제 어댑터는 지원되는 기능을 지정해야 합니다.

Astro v3.x에서는 어댑터가 지원하는 기능을 지정할 필요가 없었습니다.

Astro v4.0에서는 어댑터가 지원하는 기능 목록을 지정하기 위해 `supportedAstroFeatures{}` 속성을 전달해야 합니다. 이 속성은 더 이상 선택 사항이 아닙니다.

#### 무엇을 해야 하나요?

어댑터 작성자는 지원하는 기능 목록을 지정하기 위해 `supportedAstroFeatures{}` 옵션을 전달해야 합니다.

```js title="my-adapter.mjs" ins={9-11}
export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}
```

### 제거됨: Shiki 언어 `path` 속성

Astro v3.x에서는 `markdown.shikiConfig.langs`에 전달된 Shiki 언어가 자동으로 Shikiji 호환 언어로 변환되었습니다. Shikiji는 Astro에서 구문 강조를 위해 사용하는 내부 도구입니다.

Astro v4.0에서는 구성이 혼란스러웠던 Shiki 언어의 `path` 속성이 제거되었습니다. 이는 `langs`에 직접 전달할 수 있는 가져오기로 대체됩니다.

#### 무엇을 해야 하나요?

대신 언어 JSON 파일을 가져와서 옵션에 전달해야 합니다.

```diff lang="js"
// astro.config.js
+ import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
-       { path: '../../custom.tmLanguage.json' },
+       customLang,
      ],
    },
  },
})
```

## 더 이상 사용되지 않음

다음과 같이 더 이상 사용되지 않는 기능은 이제 지원되지 않으며, 문서화되지 않습니다. 이에 따라 프로젝트를 업데이트하세요.

일부 사용되지 않는 기능은 완전히 제거될 때까지 일시적으로 계속 작동할 수 있습니다. 또 다른 일부는 더이상 작동하지 않거나, 코드를 업데이트하라는 오류를 발생시킬 수 있습니다.

### 더 이상 사용되지 않음: View Transitions의 `submit` 이벤트를 위한 `handleForms`

Astro v3.x에서는 `<ViewTransitions />` 컴포넌트를 사용하는 프로젝트에서 `form` 요소에 대한 `submit` 이벤트 처리를 선택해야 했습니다. 이는 `handleForms` 속성을 전달하여 수행되었습니다.

Astro v4.0에서는 `<ViewTransitions />`가 사용될 때 기본적으로 `form` 요소에 대한 `submit` 이벤트를 처리합니다. `handleForms` 속성은 더 이상 사용되지 않으며 아무런 효과가 없습니다.

#### 무엇을 해야 하나요?

`ViewTransitions` 컴포넌트에서 `handleForms` 속성을 제거합니다. 더 이상 필요하지 않습니다.

```astro title="src/pages/index.astro" del="handleForms"
---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- 다른 코드 -->
  </body>
</html>
```

`submit` 이벤트 처리를 선택 해제하려면, 관련 `form` 요소에 `data-astro-reload` 속성을 추가하세요.

```astro title="src/components/Form.astro" ins="data-astro-reload"
<form action="/contact" data-astro-reload>
  <!-- -->
</form>
```

## 더 이상 사용되지 않는 기능 제거

다음과 같이 더 이상 사용되지 않는 기능은 이제 코드 베이스에서 완전히 제거되어 더 이상 사용할 수 없습니다. 이러한 기능 중 일부는 지원 중단 후에도 프로젝트에서 계속 작동할 수 있습니다. 또 다른 일부는 아무런 효과가 없었을 수도 있습니다.

이제 이러한 제거된 기능을 포함하는 프로젝트는 빌드할 수 없으며, 더 이상 이러한 기능을 제거하라는 메시지를 표시하는 문서도 지원되지 않습니다.

### 제거됨: 엔드포인트에서 단순 객체 반환

Astro v3.x에서는 엔드포인트에서 단순 객체를 반환하는 것이 더 이상 사용되지 않지만, Astro v2와의 호환성을 유지하기 위해 계속 지원되었습니다. 마이그레이션을 쉽게 하기 위해 `ResponseWithEncoding` 유틸리티도 제공되었습니다.

Astro v4.0은 단순 객체에 대한 지원을 제거하고 엔드포인트가 항상 `Response`를 반환하도록 요구합니다. 적절한 `Response` 타입을 위해 `ResponseWithEncoding` 유틸리티도 제거되었습니다.

#### 무엇을 해야 하나요?

`Response` 객체를 직접 반환하도록 엔드포인트를 업데이트하세요.

```diff lang="ts"
  export async function GET() {
-   return { body: { "title": "Bob의 블로그" }};
+   return new Response(JSON.stringify({ "title": "Bob의 블로그" }));
  }
```

`ResponseWithEncoding` 사용을 제거하려면, 대신 `ArrayBuffer`를 사용하도록 코드를 리팩토링하세요.

```diff lang="ts"
  export async function GET() {
    const file = await fs.readFile('./bob.png');
-   return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
+   return new Response(file.buffer);
  }
```

### 제거됨: `build.split` 및 `build.excludeMiddleware`

Astro v3.0에서는 `build.split` 및 `build.excludeMiddleware` 빌드 구성 옵션이 더 이상 사용되지 않으며, 동일한 작업을 수행하기 위한 [어댑터 구성 옵션](/ko/reference/adapter-reference/#어댑터-기능)으로 대체되었습니다.

Astro v4.0은 이러한 속성을 완전히 제거합니다.

#### 무엇을 해야 하나요?

더 이상 사용되지 않는 `build.split` 또는 `build.excludeMiddleware`를 사용하는 경우, 더 이상 존재하지 않으므로 이제 제거해야 합니다.

[더 이상 사용되지 않는 미들웨어 속성](/ko/guides/upgrade-to/v3/#deprecated-buildexcludemiddleware-and-buildsplit)을 어댑터 구성으로 업데이트하려면 v3 마이그레이션 안내서를 참조하세요.

### 제거됨: `Astro.request.params`

Astro v3.0에서는 `Astro.request.params` API가 더 이상 사용되지 않지만 이전 버전과의 호환성을 위해 보존되었습니다.

Astro v4.0에서는 이 옵션이 완전히 제거되었습니다.

#### 무엇을 해야 하나요?

지원되는 대체 항목인 [`Astro.params`](/ko/reference/api-reference/#astroparams)로 모두 업데이트합니다.

```astro del={1} ins={2}
const { id } = Astro.request.params;
const { id } = Astro.params;
```

### 제거됨: `markdown.drafts`

Astro v3.0에서는 `markdown.drafts`를 사용하여 초안 게시물 작성을 제어하는 ​​것이 더 이상 사용되지 않습니다.

Astro v4.0에서는 이 옵션이 완전히 제거되었습니다.

#### 무엇을 해야 하나요?

더 이상 사용되지 않는 `markdown.drafts`를 사용하는 경우, 더 이상 존재하지 않으므로 이제 제거해야 합니다.

프로젝트의 일부 페이지를 계속해서 초안으로 표시하려면, [콘텐츠 컬렉션으로 마이그레이션](/ko/guides/content-collections/#파일-기반-라우팅에서-마이그레이션)하고, 대신 `draft: true` 프런트매터 속성을 사용하여 [페이지를 수동으로 필터링](/ko/guides/content-collections/#컬렉션-쿼리-필터링)하세요.

### 제거됨: `getHeaders()`

Astro v3.0에서는 `getHeaders()` Markdown 내보내기가 더 이상 사용되지 않으며 `getHeadings()`로 대체되었습니다.

Astro v4.0에서는 이 옵션이 완전히 제거되었습니다.

#### 무엇을 해야 하나요?

더 이상 사용되지 않는 `getHeaders()`를 사용하는 경우, 더 이상 존재하지 않으므로 이제 제거해야 합니다. 모든 인스턴스를 지원되는 대체 기능인 `getHeadings()`로 바꿉니다.

```js del={2} ins={3}
const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();
```

### 제거됨: `getStaticPaths()`에서 `rss` 사용

Astro v3.0에서는 `getStaticPaths()`에서 더 이상 사용되지 않는 `rss` 도우미를 사용하면 오류가 발생합니다.

Astro v4.0은 이 도우미를 완전히 제거합니다.

#### 무엇을 해야 하나요?

RSS 피드를 생성하기 위해 더 이상 지원되지 않는 방법을 사용하고 있다면, 이제 완전한 RSS 설정을 위해 [`@astrojs/rss` 통합](/ko/guides/rss/)을 사용해야 합니다.

### 제거됨: 소문자 HTTP 메서드 이름

Astro v3.0에서는 소문자 HTTP 요청 메서드 이름 (`get`, `post`, `put`, `all`, `del`)이 더 이상 사용되지 않습니다.

Astro v4.0은 소문자 이름에 대한 지원을 완전히 제거합니다. 이제 모든 HTTP 요청 메소드는 대문자를 사용하여 작성해야 합니다.

#### 무엇을 해야 하나요?

더 이상 사용되지 않는 소문자 이름을 사용하는 경우 이제 해당 이름을 해당하는 대문자로 바꿔야 합니다.

대문자 HTTP 요청 방법을 사용하는 지침은 v3 마이그레이션 가이드를 참조하세요.

### 제거됨: `base` 접두사가 누락된 경우 301 리디렉션

Astro v3.x에서 Astro 프리뷰 서버는 기본 경로 없이 public 디렉터리 자산에 액세스할 때 301 리디렉션을 반환했습니다.

Astro v4.0은 프리뷰 서버가 실행중일 때, public 디렉터리 자산에 대해 기본 경로 접두사 없이 404 상태를 반환하여 개발 서버와 동작을 일치시킵니다.
 
#### 무엇을 해야 하나요?

Astro 프리뷰 서버를 사용할 때, public 디렉터리의 모든 정적 자산 가져오기 및 URL의 경로 앞에는 [base](/ko/reference/configuration-reference/#base) 접두사가 있어야 합니다.

다음 예시는 `base: '/docs'`가 구성된 경우, public 폴더의 이미지를 표시하는 데 필요한 `src` 속성을 보여줍니다.

```astro title="src/pages/index.astro" ins="/docs"
// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">
```

### 제거됨: `astro/client-image` 자동 변환

Astro v3.x에서는 `astro/client-image` 타입(더 이상 사용되지 않는 이미지 통합에 사용됨)이 제거되었지만, `env.d.ts` 파일에 있는 경우, 기본 Astro 타입인 `astro/client`로 자동 변환되었습니다.

Astro v4.0은 `astro/client-image`를 무시하고 더 이상 `env.d.ts`를 자동으로 업데이트하지 않습니다.

#### 무엇을 해야 하나요?

`src/env.d.ts` 파일에 `@astrojs/image`에 대한 타입이 구성되어 있고 v3.0으로 업그레이드해도 타입이 자동으로 변환되지 않는 경우, 수동으로 `astro/client-image` 타입을 `astro/client`로 바꾸세요.

```ts title="src/env.d.ts" del={1} ins={2}
  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />
```

## 커뮤니티 자료

Astro v4.0에 대한 좋은 리소스를 알고 계십니까? [이 페이지를 편집](https://github.com/withastro/docs/edit/main/src/content/docs/ko/guides/upgrade-to/v4.mdx)하고 아래에 링크를 추가하세요!

## 알려진 문제

보고된 문제가 있는지 [GitHub에서 Astro의 issues](https://github.com/withastro/astro/issues/)를 확인하거나 직접 문제를 보고해주세요.
